home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d1 / dostra.arc / DOSTRACE.DOC < prev    next >
Text File  |  1991-01-06  |  7KB  |  220 lines
  1.                   DOSTRACE
  2.  
  3.  Dostrace is a TSR Utility that will allow you to trace and display the DOS
  4.  operating  system calls your program is making.
  5.  
  6.  Dostrace requires a 80286 processor, or better running DOS. It also requires
  7.  a color montior.
  8.  
  9.  In addition to tracing operating system calls it will also show you : 
  10.  
  11.   1) what files are open, and the last IO operation against them. 
  12.  
  13.   2) The current PSP.
  14.  
  15.   3) The current environment.
  16.  
  17.   4) a Memory map of your system.
  18.  
  19.   5) Display and edit any memory location. (You cannot edit ROM).
  20.  
  21.   6) Display the value of the CPU registers for the executing program.
  22.  
  23.   7) Watch a specified area of memory and Break when it changes.
  24.  
  25.   After loading Dostrace you activate it by pressing left_shift-F1.
  26.   You will see a menu with the following Options.
  27.  
  28.     Trace Table
  29.         Psp
  30.         Environment
  31.         File Table
  32.         Memory Map
  33.         Storage
  34.         Watch
  35.         Break
  36.         Registers
  37.         Display
  38.         Uninstall
  39.  
  40.  Press the first letter of any menu item to select that item.
  41.  
  42.  Trace Table.
  43.  ++++++++++++
  44.   
  45.     The trace table stores the last 100 calls made to the operating system
  46.     the general layout of a trace entry is.
  47.  
  48.   (1)    (2)      (3)         <------- 4 --------> (5)   (6)
  49.   1234  READ   DOSTRACE.COM  0005:0060  3BD6 0000 0060  0246
  50.  
  51.   (1). This is a counter of the number of calls made to the operating system.
  52.        It will reset at 10,000
  53.  
  54.   (2)  This is the type of operating system request.
  55.  
  56.   (3)  This is the file,program etc that the request was made against.
  57.  
  58.   (4)  This is useful data for the type of request. In this example they
  59.        are :
  60.            0005      = The file Handle
  61.            0060      = number of bytes to read
  62.            3BD6 0000 = address to read the data into          
  63.          
  64.   (5) The return code from DOS. In this examples the number of bytes read.
  65.  
  66.   (6) The value of the Flags register.
  67.  
  68.   Dostrace will only store 100 entrys. After that the trace table WRAPS by 
  69.   discarding the oldest entry. 
  70.  
  71.   Dostrace does not trace all possible DOS Calls.
  72.  
  73.  Psp.
  74.  ++++
  75.  
  76.    This selections allows you to display, and edit the current PSP.
  77.  
  78.  Environment.
  79.  ++++++++++++
  80.  
  81.    This selection allows you to display, and edit the currently executing 
  82.    programs Environment.
  83.  
  84.  File Table.
  85.  +++++++++++
  86.  
  87.    This selection shows you what files are open on your system. The layout 
  88.    is as follows.
  89.  
  90.     (1)  (2)        (3)           (4)  (5)     (6)
  91.     20  1DFA     3800:0000       0020   R   DOSTRACE.ASM    
  92.  
  93.     1 = file handle from DOS.
  94.         2 = Owning PSP address.
  95.         3 = address of last read/write buffer.
  96.         4 = number of bytes for the last read write operation
  97.         5 = R if last operation was a read. W if it was a write.
  98.         6 = the file name.
  99.  
  100.    The file table will keep track of 40 files.
  101.  
  102.    File handles 0-4 are not displayed unless they have been closed and opened
  103.    as new files.
  104.  
  105.  Memory Map.
  106.  +++++++++++
  107.  
  108.    This    selection will show you how memory is being used by programs and
  109.    TSRs on your computer. The display layout is as follows.
  110.  
  111.    (1)        (2)       (3)             (4)           (5)
  112.   Address     Size        Owner            Type         Parent    
  113.  
  114.    0DE4       0010        0DF5 DOSEDIT     ENV       
  115.    0DF5       007B        0DF5 DOSEDIT     PSP    0CCB DOS
  116.    67F8       3800        FREE     
  117.  
  118.     1 = The address of the memory block.
  119.         2 = The size of the memory block, in paragraphs. (1 paragraph = 16 bytes)      
  120.     3 = The address of the PSP that owns this block and, if dostrace can
  121.             determine it, the owning programs name. If this block of memory is 
  122.             free the owner is shown as FREE.
  123.         4 = the type of memory. ENV = Program environment.
  124.                                 PSP = Program PSP and its associated code.
  125.                                 MEM = program memory allocated via an operating
  126.                                       system call.
  127.         5 = if the type is PSP this will show the parents PSP and, if dostrace
  128.             can determine it the parent programs name.
  129.  
  130.    The currently active program will be shown in yellow.
  131.  
  132.  Storage.
  133.  ++++++++
  134.     
  135.    This selection allows you to enter a memory address, in hex. The program
  136.    will then display, and allow you to edit, memory at that address. you can 
  137.    use page up, page down and the cursor keys to scroll through memory.
  138.  
  139.  Watch.
  140.  ++++++
  141.  
  142.    Watch allows you to enter a memory address and a length. Dostrace then uses
  143.    the single step feature of the processor to monitor that memory area. 
  144.    If the area    is changed Dostrace will POP-UP telling you where in the memory
  145.    area the change was made. You may then make use of the dostrace features
  146.    to determine which area of your program made the change.
  147.  
  148.  
  149.  Break.
  150.  ++++++
  151.  
  152.    This option allows you to enter a DOS Function Code, in Hex (i.e 3D = OPEN FILE),
  153.    and an optional character of (G)ood return from DOS (B)ad return from DOS
  154.    or (A)ll. Dostrace will then break when ever a program makes that DOS call
  155.    and will display the trace table at the entry for that call. This option
  156.    can be deactivated by selecting Break from the menu and pressing ESC.
  157.        
  158.  Registers.
  159.  ++++++++++
  160.  
  161.    This option shows you the value of the CPU registers at the time you
  162.    pressed left_shift-F1.
  163.  
  164.  
  165.  Display.
  166.  ++++++++
  167.  
  168.    This option shows you the current programs screen image.     
  169.  
  170.  Uninstall.
  171.  ++++++++++
  172.  
  173.    This option Uninstalls Dostrace and frees up any memory allocated to it.
  174.    If a subsequent TSR or the current program has hooked into an interrupt
  175.    that Dostrace uses you will get the message 'CANNOT UNINSTALL'  
  176.  
  177.  
  178.  
  179.   Startup Parameters.
  180.   +++++++++++++++++++
  181.  
  182.    Dostrace currently accepts two start up parameters -e and -f :
  183.  
  184.    -e will attempt to place the trace table in expanded memory. If
  185.    none is found Dostrace will use conventional memory.
  186.  
  187.    -f<file_name> will trace entrys to the file specified by file_name.
  188.    this will continue until your disk fills up or you uninstall Dostrace.
  189.    Registered users will receive an EXE that will display the contents of
  190.    this file in a readable form.
  191.  
  192.  
  193.    Dostrace will also break and display a message if your program attempts
  194.    to execute an invalid instruction. You may then use any of the above
  195.    features to try and determine what went wrong. On exiting Dostrace, by
  196.    pressing the escape key, Dostrace will attempt to close any open files
  197.    your program may have and terminate your program in an orderly fashion.
  198.    The success of this depends on how much damage your program did before
  199.    the invalid instruction.
  200.  
  201.  
  202.    Dostrace is distributed as is. Please feel free to copy it. 
  203.    If you find this product useful and would like to register for free
  204.    upgrades and a more comprehensive manual send $25 to the address below.
  205.    If you would like the source code and make file for Dostrace plus the
  206.    manual send $60 to the address below. If you have any questions, comments
  207.    or problems you can email me at CIS (ID 71507,1033).      
  208.   
  209.                 Steve Bridges
  210.           1391 union street
  211.               Manchester NH 03104.    
  212.        
  213.      
  214.  
  215.  
  216.  
  217.        
  218.         
  219.  
  220.